PyDicom API Tutorial

1. Introduction to PyDicom

PyDicom is a pure Python package for working with DICOM (Digital Imaging and Communications in Medicine) files. DICOM is the international standard for medical images and related information, commonly used for CT scans, MRI scans, X-rays, and other medical imaging modalities.

Why DICOM Matters in Medical Imaging

DICOM is not just about images—it's a comprehensive standard that ensures medical imaging data can be shared, stored, and interpreted consistently across different healthcare systems worldwide. When a CT scanner creates an image, it packages not only the pixel data but also critical information about:

• Patient demographics: Name, ID, age, sex, and medical history
• Study details: When and why the scan was performed
• Acquisition parameters: Machine settings, radiation dose, contrast agents
• Image characteristics: Dimensions, spacing, orientation in 3D space
• Clinical context: Physician notes, diagnoses, and measurements

What Makes PyDicom Powerful?

PyDicom bridges the gap between complex medical imaging standards and Python's data science ecosystem. It enables:

• Easy file access: Read and write DICOM files with simple Python commands
• Rich metadata extraction: Access thousands of data points beyond just pixel data
• Integration capabilities: Work seamlessly with NumPy, Pandas, and machine learning libraries
• Clinical workflows: Build tools for radiologists, researchers, and healthcare IT systems
• Pythonic interface: Manipulate complex medical data structures using familiar Python patterns

2. Installation and Setup

Installing PyDicom

# Using pip
pip install pydicom

# For additional image processing capabilities
pip install pydicom[numpy]

# For displaying images
pip install matplotlib

Basic Imports

import pydicom
import numpy as np
import matplotlib.pyplot as plt
from pathlib import Path

3. Understanding DICOM Files

What is DICOM?

DICOM (Digital Imaging and Communications in Medicine) is much more than a file format—it's a comprehensive standard that defines how medical images are formatted, stored, transmitted, and displayed. Developed in the 1980s and continuously updated, DICOM ensures that a CT scan taken in Tokyo can be viewed and analyzed in New York without any loss of information or meaning.

DICOM File Structure

A DICOM file (.dcm) is organized into several key components:

DICOM Tags: The Key to Everything

Every piece of information in a DICOM file is identified by a unique tag—a pair of hexadecimal numbers that act like an address in the file structure. Think of DICOM tags like a massive, standardized dictionary where each entry has a specific meaning recognized worldwide.

Tag Format: (GGGG, EEEE)

• GGGG (Group): The first number groups related attributes together (e.g., all patient info, all image properties)
• EEEE (Element): The second number identifies the specific attribute within that group

Examples:

• (0010, 0010) → Patient's Name
• (0028, 0010) → Number of Rows in the image
• (0018, 0050) → Slice Thickness in millimeters
• (7FE0, 0010) → The actual Pixel Data

Common DICOM Groups and Their Purpose

Understanding CT Scan Specifics

CT (Computed Tomography) scans have unique characteristics in DICOM:

DICOM Hierarchy: Study → Series → Instance

Medical imaging data is organized hierarchically:

Why this matters: When working with CT scans, you'll typically process an entire series of images that together form a 3D volume of the scanned region.

4. Core PyDicom Classes

PyDicom's architecture revolves around three fundamental classes that mirror the structure of DICOM files. Understanding these classes is essential for effectively working with medical imaging data.

The PyDicom Class Hierarchy

1. DataSet Class

The DataSet is the container that holds all DICOM information. Think of it as a specialized Python dictionary where:

• Keys are DICOM tags (like (0010, 0010) for Patient Name)
• Values are DataElements that contain the actual information plus metadata about how it's stored
• Flexible access allows you to retrieve data by tag, keyword, or attribute name

When you read a DICOM file with pydicom.dcmread(), you get back a DataSet object containing everything from the file.

2. DataElement Class

Each DataElement represents a single piece of DICOM information. Every DataElement has four key components:

3. Sequence Class

A Sequence is a special type of DataElement that contains a list of DataSets. This allows DICOM to represent hierarchical or repeating information, such as:

• Multiple referenced images
• Series of measurements
• Nested protocol information
• Code sequences with multiple items

Sequences are like arrays of sub-dictionaries, enabling complex nested data structures within a single DICOM file.

Value Representation (VR) Types

The VR tells PyDicom how to interpret the raw bytes in a DICOM file. Different VRs map to different Python types:

5. Reading DICOM Files

Basic File Reading

# Read a single DICOM file
dicom_data = pydicom.dcmread('path/to/file.dcm')

# Read with specific options
dicom_data = pydicom.dcmread('scan.dcm', 
                              force=True,  # Read even if not compliant
                              stop_before_pixels=False)  # Load pixel data

Reading Multiple Files

import os

def read_dicom_series(directory):
    """Read all DICOM files from a directory"""
    dicom_files = []
    
    for filename in os.listdir(directory):
        if filename.endswith('.dcm'):
            filepath = os.path.join(directory, filename)
            try:
                ds = pydicom.dcmread(filepath)
                dicom_files.append(ds)
            except Exception as e:
                print(f"Error reading {filename}: {e}")
    
    return dicom_files

# Usage
series = read_dicom_series('ct_scan_folder/')
print(f"Loaded {len(series)} DICOM files")

Checking if File is DICOM

def is_dicom_file(filepath):
    """Check if a file is a valid DICOM file"""
    try:
        pydicom.dcmread(filepath, stop_before_pixels=True)
        return True
    except:
        return False

6. Working with DataSet

Accessing DICOM Attributes

There are multiple ways to access DICOM data:

patient_name = dicom_data.PatientName
print(f"Patient: {patient_name}")

patient_name = dicom_data[0x0010, 0x0010].value
print(f"Patient: {patient_name}")

patient_name = dicom_data['PatientName'].value
print(f"Patient: {patient_name}")

study_desc = dicom_data.get('StudyDescription', 'Unknown Study')

Essential DataSet Methods

.keys() - Get All Tags

# Get all DICOM tags in the file
tags = dicom_data.keys()
print(f"Total tags: {len(tags)}")

# Iterate through tags
for tag in list(tags)[:5]:  # First 5 tags
    print(tag)

.dir() - Get Alphabetical Keyword List

# Get all keywords
keywords = dicom_data.dir()
print(f"Available attributes: {len(keywords)}")

# Filter keywords
pixel_keywords = dicom_data.dir('Pixel')
print(f"Pixel-related attributes: {pixel_keywords}")

# Filter for patient info
patient_keywords = dicom_data.dir('Patient')
print(f"Patient attributes: {patient_keywords}")

.group_dataset() - Filter by Group

# Get all Image Pixel attributes (group 0x0028)
image_info = dicom_data.group_dataset(0x0028)
print(image_info)

# Get all Patient Information (group 0x0010)
patient_info = dicom_data.group_dataset(0x0010)
for element in patient_info:
    print(f"{element.keyword}: {element.value}")

.elements() - Get Top-Level Elements Only

# Get top-level elements (excludes nested sequences)
top_elements = list(dicom_data.elements())
print(f"Top-level elements: {len(top_elements)}")

Checking for Attribute Existence

# Check if attribute exists
if 'PatientName' in dicom_data:
    print(f"Patient Name: {dicom_data.PatientName}")

# Using hasattr
if hasattr(dicom_data, 'SeriesDescription'):
    print(f"Series: {dicom_data.SeriesDescription}")

# Safe access with get()
contrast = dicom_data.get('ContrastBolusAgent', 'Not specified')

7. Working with DataElements

Anatomy of a DataElement

# Get a specific data element
element = dicom_data[0x0010, 0x0010]

# Access element properties
print(f"Tag: {element.tag}")           # (0010, 0010)
print(f"Keyword: {element.keyword}")   # PatientName
print(f"VR: {element.VR}")             # PN (Person Name)
print(f"Value: {element.value}")       # The actual patient name
print(f"Name: {element.name}")         # Patient's Name

Working with Different VR Types

# String values (PN, LO, SH)
patient_name = dicom_data.PatientName
print(type(patient_name))  # str or PersonName

# Numeric values (DS, IS)
slice_thickness = float(dicom_data.SliceThickness)
rows = int(dicom_data.Rows)

# Date/Time values
study_date = dicom_data.StudyDate  # Format: YYYYMMDD
print(f"Study Date: {study_date}")

# Multiple values (stored as list)
window_center = dicom_data.WindowCenter
print(f"Window Centers: {window_center}")  # May be [value1, value2]

Creating Custom DataElements

from pydicom import Dataset
from pydicom.dataelem import DataElement

# Create a new dataset
new_ds = Dataset()

# Add elements using attribute assignment
new_ds.PatientName = "Doe^John"
new_ds.PatientID = "12345"
new_ds.Modality = "CT"

# Add element using DataElement
elem = DataElement(0x00100020, 'LO', 'ABC123')
new_ds[0x00100020] = elem

8. Working with Sequences

Sequences are DICOM attributes that contain nested datasets. They're used for complex hierarchical data.

# Find all sequence attributes
sequences = dicom_data.dir('Sequence')
print(f"Sequences found: {sequences}")

# Access a sequence
if 'ReferencedImageSequence' in dicom_data:
    seq = dicom_data.ReferencedImageSequence
    print(f"Sequence length: {len(seq)}")
    
    # Iterate through sequence items
    for i, item in enumerate(seq):
        print(f"\nItem {i}:")
        print(item)

Working with Nested Data

# Example: DeidentificationMethodCodeSequence
if 'DeidentificationMethodCodeSequence' in dicom_data:
    deident_seq = dicom_data.DeidentificationMethodCodeSequence
    
    # Access specific item
    first_item = deident_seq[0]
    code_value = first_item.CodeValue
    code_meaning = first_item.CodeMeaning
    
    print(f"Code: {code_value} - {code_meaning}")
    
    # Iterate through all items
    for item in deident_seq:
        if hasattr(item, 'CodeMeaning'):
            print(f"- {item.CodeMeaning}")

Creating Sequences

from pydicom import Dataset
from pydicom.sequence import Sequence

# Create main dataset
ds = Dataset()

# Create sequence items
item1 = Dataset()
item1.CodeValue = "001"
item1.CodeMeaning = "First Code"

item2 = Dataset()
item2.CodeValue = "002"
item2.CodeMeaning = "Second Code"

# Create sequence and add items
seq = Sequence([item1, item2])
ds.CustomSequence = seq

9. Extracting Pixel Data and Images

While DICOM metadata is crucial, the primary reason for medical imaging is the images themselves. PyDicom makes it easy to extract and work with pixel data, converting it from DICOM's specialized format into NumPy arrays for analysis and visualization.

Understanding Medical Image Data

Unlike regular photographs, medical images have specific characteristics:

• Grayscale: Most medical images are single-channel (not RGB color)
• High bit depth: CT scans typically use 12-16 bits per pixel (not 8-bit like regular images)
• Physical measurements: Pixel values represent actual tissue densities, not just visual brightness
• Calibrated data: Values need conversion formulas to get meaningful units (like Hounsfield Units for CT)

Getting Pixel Array

# Extract pixel data as numpy array
pixel_array = dicom_data.pixel_array

print(f"Image shape: {pixel_array.shape}")
print(f"Data type: {pixel_array.dtype}")
print(f"Min value: {pixel_array.min()}")
print(f"Max value: {pixel_array.max()}")

Understanding Image Parameters

To properly interpret and display medical images, you need to understand their physical properties:

# Get image dimensions
rows = dicom_data.Rows
cols = dicom_data.Columns
print(f"Image size: {rows} x {cols}")

# Get pixel spacing (physical dimensions)
if 'PixelSpacing' in dicom_data:
    pixel_spacing = dicom_data.PixelSpacing
    print(f"Pixel spacing: {pixel_spacing[0]} x {pixel_spacing[1]} mm")

# Get slice thickness
if 'SliceThickness' in dicom_data:
    print(f"Slice thickness: {dicom_data.SliceThickness} mm")

Applying Window/Level for Display

Medical images often have a much wider range of values than can be displayed on a screen. Windowing (also called window/level adjustment) selects which range of values to display, making specific tissues visible.

def apply_windowing(pixel_array, window_center, window_width):
    """Apply window/level for proper image display"""
    img_min = window_center - window_width / 2
    img_max = window_center + window_width / 2
    
    windowed = np.clip(pixel_array, img_min, img_max)
    windowed = (windowed - img_min) / (img_max - img_min) * 255
    
    return windowed.astype(np.uint8)

# Get window parameters from DICOM
if 'WindowCenter' in dicom_data and 'WindowWidth' in dicom_data:
    wc = float(dicom_data.WindowCenter[0] if isinstance(dicom_data.WindowCenter, list) 
               else dicom_data.WindowCenter)
    ww = float(dicom_data.WindowWidth[0] if isinstance(dicom_data.WindowWidth, list) 
               else dicom_data.WindowWidth)
    
    windowed_image = apply_windowing(pixel_array, wc, ww)

Applying Rescale Slope and Intercept

Raw pixel values in DICOM files often need transformation to become clinically meaningful. For CT scans, this converts stored values to Hounsfield Units (HU), which represent tissue density.

def convert_to_hounsfield(pixel_array, dicom_data):
    """Convert pixel values to Hounsfield Units (HU)"""
    intercept = float(dicom_data.RescaleIntercept)
    slope = float(dicom_data.RescaleSlope)
    
    hu_array = pixel_array * slope + intercept
    return hu_array

# Apply conversion
if 'RescaleSlope' in dicom_data and 'RescaleIntercept' in dicom_data:
    hu_image = convert_to_hounsfield(pixel_array, dicom_data)
    print(f"HU range: {hu_image.min()} to {hu_image.max()}")

Complete Image Display Function

Here's a comprehensive function that handles all the steps needed to properly display a DICOM image:

import matplotlib.pyplot as plt

def display_dicom_image(dicom_data):
    """Display a DICOM image with proper windowing"""
    
    # Get pixel array
    img = dicom_data.pixel_array
    
    # Apply rescale if available
    if 'RescaleSlope' in dicom_data and 'RescaleIntercept' in dicom_data:
        img = convert_to_hounsfield(img, dicom_data)
    
    # Display
    plt.figure(figsize=(10, 10))
    plt.imshow(img, cmap='gray')
    plt.axis('off')
    
    # Add title with metadata
    title = f"Patient: {dicom_data.get('PatientID', 'Unknown')}\n"
    title += f"Study: {dicom_data.get('StudyDescription', 'N/A')}"
    plt.title(title)
    
    plt.tight_layout()
    plt.show()

# Usage
display_dicom_image(dicom_data)

10. Practical Examples

Example 1: Extract Patient Demographics

def extract_patient_info(dicom_data):
    """Extract comprehensive patient information"""
    
    patient_info = {
        'Patient ID': dicom_data.get('PatientID', 'Unknown'),
        'Patient Name': str(dicom_data.get('PatientName', 'Unknown')),
        'Birth Date': dicom_data.get('PatientBirthDate', 'Unknown'),
        'Age': dicom_data.get('PatientAge', 'Unknown'),
        'Sex': dicom_data.get('PatientSex', 'Unknown'),
        'Weight': dicom_data.get('PatientWeight', 'Unknown'),
    }
    
    return patient_info

# Usage
info = extract_patient_info(dicom_data)
for key, value in info.items():
    print(f"{key}: {value}")

Example 2: Extract Study Information

def extract_study_info(dicom_data):
    """Extract study and series information"""
    
    study_info = {
        'Study Date': dicom_data.get('StudyDate', 'Unknown'),
        'Study Time': dicom_data.get('StudyTime', 'Unknown'),
        'Study Description': dicom_data.get('StudyDescription', 'Unknown'),
        'Modality': dicom_data.get('Modality', 'Unknown'),
        'Manufacturer': dicom_data.get('Manufacturer', 'Unknown'),
        'Model': dicom_data.get('ManufacturerModelName', 'Unknown'),
        'Series Description': dicom_data.get('SeriesDescription', 'Unknown'),
        'Series Number': dicom_data.get('SeriesNumber', 'Unknown'),
        'Instance Number': dicom_data.get('InstanceNumber', 'Unknown'),
    }
    
    return study_info

Example 3: Create Metadata DataFrame

import pandas as pd

def create_metadata_dataframe(dicom_files):
    """Create a pandas DataFrame from multiple DICOM files"""
    
    metadata_list = []
    
    for dcm_file in dicom_files:
        try:
            ds = pydicom.dcmread(dcm_file)
            
            metadata = {
                'Filename': dcm_file,
                'PatientID': ds.get('PatientID', ''),
                'PatientName': str(ds.get('PatientName', '')),
                'StudyDate': ds.get('StudyDate', ''),
                'Modality': ds.get('Modality', ''),
                'SeriesDescription': ds.get('SeriesDescription', ''),
                'InstanceNumber': ds.get('InstanceNumber', ''),
                'SliceLocation': ds.get('SliceLocation', ''),
                'Rows': ds.get('Rows', ''),
                'Columns': ds.get('Columns', ''),
            }
            
            metadata_list.append(metadata)
            
        except Exception as e:
            print(f"Error processing {dcm_file}: {e}")
    
    df = pd.DataFrame(metadata_list)
    return df

Example 4: Sort DICOM Series by Slice Location

def sort_dicom_series(dicom_files):
    """Sort DICOM files by slice location"""
    
    # Read all files and extract slice location
    slices = []
    for filepath in dicom_files:
        ds = pydicom.dcmread(filepath)
        slices.append((filepath, ds.get('SliceLocation', 0)))
    
    # Sort by slice location
    slices.sort(key=lambda x: float(x[1]))
    
    # Return sorted file paths
    return [filepath for filepath, _ in slices]

Example 5: Create 3D Volume from Series

def create_3d_volume(dicom_directory):
    """Create a 3D numpy array from a DICOM series"""
    
    # Get all DICOM files
    files = [os.path.join(dicom_directory, f) 
             for f in os.listdir(dicom_directory) 
             if f.endswith('.dcm')]
    
    # Sort by instance number
    slices = []
    for filepath in files:
        ds = pydicom.dcmread(filepath)
        slices.append((ds, float(ds.get('InstanceNumber', 0))))
    
    slices.sort(key=lambda x: x[1])
    
    # Get dimensions
    first_slice = slices[0][0]
    rows = first_slice.Rows
    cols = first_slice.Columns
    
    # Create 3D array
    volume = np.zeros((len(slices), rows, cols))
    
    # Fill the volume
    for i, (ds, _) in enumerate(slices):
        volume[i] = ds.pixel_array
    
    return volume

# Usage
# volume = create_3d_volume('ct_series/')
# print(f"Volume shape: {volume.shape}")

Example 6: Anonymize DICOM Files

def anonymize_dicom(dicom_data, patient_id_prefix="ANON"):
    """Remove or replace identifying information"""
    
    # Generate anonymous ID
    anon_id = f"{patient_id_prefix}_{hash(str(dicom_data.SOPInstanceUID)) % 10000:04d}"
    
    # Tags to anonymize
    tags_to_anonymize = [
        'PatientName', 'PatientID', 'PatientBirthDate',
        'PatientAge', 'InstitutionName', 'ReferringPhysicianName'
    ]
    
    for tag in tags_to_anonymize:
        if hasattr(dicom_data, tag):
            if tag == 'PatientID':
                setattr(dicom_data, tag, anon_id)
            elif tag == 'PatientName':
                setattr(dicom_data, tag, f"Anonymous^{anon_id}")
            else:
                delattr(dicom_data, tag)
    
    return dicom_data

11. Best Practices

Error Handling

def safe_dicom_read(filepath):
    """Safely read DICOM file with error handling"""
    try:
        ds = pydicom.dcmread(filepath)
        return ds, None
    except pydicom.errors.InvalidDicomError:
        return None, "Not a valid DICOM file"
    except FileNotFoundError:
        return None, "File not found"
    except Exception as e:
        return None, f"Unexpected error: {str(e)}"

# Usage
ds, error = safe_dicom_read('scan.dcm')
if error:
    print(f"Error: {error}")
else:
    print("Successfully loaded DICOM file")

Memory Management for Large Series

def process_large_series(directory, processing_func):
    """Process large DICOM series without loading all into memory"""
    
    files = [f for f in os.listdir(directory) if f.endswith('.dcm')]
    results = []
    
    for i, filename in enumerate(files):
        filepath = os.path.join(directory, filename)
        
        # Read, process, and release
        ds = pydicom.dcmread(filepath)
        result = processing_func(ds)
        results.append(result)
        
        # Explicitly delete to free memory
        del ds
        
        if (i + 1) % 10 == 0:
            print(f"Processed {i + 1}/{len(files)} files")
    
    return results

Validation

def validate_dicom_file(dicom_data):
    """Validate essential DICOM attributes"""
    
    required_attrs = [
        'PatientID', 'StudyInstanceUID', 'SeriesInstanceUID',
        'SOPInstanceUID', 'Modality', 'Rows', 'Columns'
    ]
    
    missing = []
    for attr in required_attrs:
        if not hasattr(dicom_data, attr):
            missing.append(attr)
    
    if missing:
        print(f"Missing required attributes: {missing}")
        return False
    
    print("DICOM file validation passed")
    return True

Summary

PyDicom provides a powerful and intuitive interface for working with DICOM files in Python. Key takeaways:

• DataSet is the main class representing DICOM data as a dictionary
• DataElements are the individual pieces of information, each with a tag, keyword, VR, and value
• Sequences allow for nested hierarchical data structures
• Multiple access methods provide flexibility: attribute names, tags, or keywords
• Rich metadata beyond just pixel data enables comprehensive medical image analysis
• Proper error handling and memory management are essential for production code